/**
 * OSAmI: Open Source Ambient Intelligence
 * A simple discovery protocol (based on multicast communications) for constrained devices.
 * Copyright (C) Lionel Debroux 2006 (as a TER/Magistere M1 student in the LSR-IMAG-ADELE team, for a demo in the H-Omega project)
 * Copyright (C) Lionel Debroux 2010 (as an engineer in the LCIS-INPG-CTSYS team, for a pre-demo in the FR part of the OSAMI project)
 * Contact: osami-general@osami-commons.org
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation;
 * version 2.1 of the License.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Suite 500 Boston, MA 02110-1335 USA
 */

package fr.imag.adele.homega.impl.discovery;

import java.io.IOException;

/**
 * This interface defines the externally usable methods of devices, and several constant strings used by the other classes
 * of the same package. Having those defined in a single place makes it easier to change the format. 
 */
public interface Device {
	
	/**
	 * Send "Hello" discovery message.
	 * @throws IOException 
	 */
	public void hello() throws IOException;

	/**
	 * Send "Bye" discovery message.
	 * @throws IOException 
	 */
	public void bye() throws IOException;

	/**
	 * Add metadata.
	 * @param property the name of the property (key)
	 * @param value the value of the property
	 */
	public void addMetadata(String property, String value);

	/**
	 * Remove metadata.
	 * @param property the property (key) to remove
	 */
	public void removeMetadata(String property);

	/**
	 * Get metadata
	 * @param property the property (key) to retrieve, null if not found
	 */
	public String getMetadata(String property);

	/**
	 * Callback for receiving messages.
	 * @param topic the topic (address) on which the message is received.
	 * @param message the message
	 */
	public void receive(String topic, String message);

	/**
	 * Send a message.
	 * @param topic the topic (address) on which the message should be sent
	 * @param port the port
	 * @param message the message
	 * @throws IOException
	 */
	public void send(String topic, int port, String message) throws IOException;

	/**
	 * Send an Event for the event bridge.
	 * @param event the event
	 * @throws IOException
	 */
	public void sendEvent(DeviceEvent event) throws IOException;

	/**
	 * Shutdown this device.
	 */
	public void shutdown();


	/**
	 * String for the field separator in the discovery and event messages.
	 */
	public static final String DEVICE_FIELD_SEPARATOR = "!";

	/**
	 * Magic + version number leading discovery and event messages.
	 */
	public static final String DEVICE_PROTOCOL_VERSION = "O1";

	/**
	 * Prefix string for a "Hello" discovery message.
	 */
	public static final String DEVICE_HELLO_PREFIX = DEVICE_PROTOCOL_VERSION + "H"; // HELLO

	/**
	 * Prefix string for a "Probe" discovery message.
	 */
	public static final String DEVICE_PROBE_PREFIX = DEVICE_PROTOCOL_VERSION + "P"; // PROBE

	/**
	 * Prefix string for a "Bye" discovery message.
	 */
	public static final String DEVICE_BYE_PREFIX = DEVICE_PROTOCOL_VERSION + "B"; // BYE

	/**
	 * Prefix string for a "Get metadata" (request) discovery message.
	 */
	public static final String DEVICE_GETMETADATA_PREFIX = DEVICE_PROTOCOL_VERSION + "G"; // GETMETADATA

	/**
	 * Prefix string for a "Metadata" (reply) discovery message.
	 */
	public static final String DEVICE_METADATA_PREFIX = DEVICE_PROTOCOL_VERSION + "M"; // METADATA

	/**
	 * Prefix string for an Event message.
	 */
	public static final String DEVICE_EVENT_PREFIX = DEVICE_PROTOCOL_VERSION + "E"; // EVENT
}
